﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>Untitled Page</title>
</head>
<body>

    <h1>
        Connection Handling</h1>
    <p>
        There are two types of CIPl attributes you can attach to a C# class</p>
    <ul>
        <li>CIP4ItemAttribute - which defines the characteristics of the class that are 
            invariant across all data providers</li>
        <li>CIP4ConnectionAttribute subtypes - which are specific to the data provider 
        and provide settings required by the store</li>
    </ul>
    <p>
        You can get a list of the currently available CIP4ConnectionAttribute types by 
        running
    </p>
    <pre>CIP4.Installer /action list</pre>
    <p>
        The application will return a list somewhat as follows - which of these you can 
        use will depend on what you have installed in the local environment.
    </p>
    <pre>
Available connection types and their parameters:
================================================
Sql:
        Database:String
        Host:String
        UserId:String
        Password:String
        CacheConnection:CIP4ConnectionAttribute
MySql:
        Database:String
        Host:String
        UserId:String
        Password:String
        CacheConnection:CIP4ConnectionAttribute
Mosso:
        UserName:String
        AccessKey:String
        CacheConnection:CIP4ConnectionAttribute
S3:
        AccessKey:String
        SecretKey:String
        CacheConnection:CIP4ConnectionAttribute
XmlFile:
        XmlFileName:String
        CacheConnection:CIP4ConnectionAttribute
File:
        BaseDirectoryPath:String
        CacheConnection:CIP4ConnectionAttribute
Dictionary:
        BaseDirectoryPath:String
        CacheConnection:CIP4ConnectionAttribute
Cassandra:
        Keyspace:String
        ColumnFamily:String
        CacheConnection:CIP4ConnectionAttribute
MongoDB:
        Server:String
        Port:Int32
        Database:String
        CacheConnection:CIP4ConnectionAttribute
Migrator:
        Target:CIP4ConnectionAttribute
        Source:CIP4ConnectionAttribute
        CacheConnection:CIP4ConnectionAttribute    </pre>

    <h2>
        Providing Connection Values</h2>
    <p>
        There are three ways to provide connection values</p>
    <ol>
        <li>As a part of the class definition</li>
        <li>When constructing the class wrapper</li>
        <li>Via a delegate attached to the wrapper</li>
    </ol>
    <h3>
        1. Class Definition</h3>
    <p>
        The connection attribute can be defined in the class declaration using the usual 
        C# conventions - for example</p>
    <pre>
    [CIP4Item(AddAllProperties=true, Collection="People"),
     CIP4DictionaryConnection(BaseDirectoryPath = "c:\\temp\\PeopleData")]
    public class PersonType
    {
        public static StrongWrapper&lt;PersonType&gt; Wrapper = new StrongWrapper&lt;PersonType&gt;(Globals.DefaultLogger);

        [CIP4ExternalID]
        public string Name { get; set; }
        public string Address { get; set; }
    }
    </pre>
    <p>
        The approach has limited value as it requires the various connection parameters 
        to be defined as constants in the application source (C# attributes do not allow 
        general expressions in attribute parameter assignments)</p>
    <h3>
        2. Wrapper</h3>
    <p>
        The connection attribute can be provided as a parameter to the wrapper - for 
        example</p>
    <pre>
            StrongWrapper&lt;PersonType&gt; wrapper = new StrongWrapper&lt;PersonType&gt;(
                new CIP4DictionaryConnectionAttribute { 
			BaseDirectoryPath = Path.Combine(Environment.CurrentDirectory, "PeopleData") },
                Globals.DefaultLogger);
  </pre>
    <p>
        &nbsp;</p>
    <h3>
        3. Delegate</h3>

    <p>
        The connection attribute values can be provided by the GetValues delegate 
        defined on the wrapper - for example</p>
    <pre>
            PersonType.Wrapper.GetValues = delegate(Dictionary&lt;string, string&gt; values)
            {
                values.Add("XmlFileName", "c:\\temp\\PeopleData\\People.xml");
                return ProviderTypesEnum.XmlFile;
            };
    </pre>
    <p>
        This is the most awkward to use because you have to know what value to provide 
        in the values dictionary for a given ProviderTypesEnum value - these values 
        (including the appropriate enum value) can be obtained by running </p>
    <pre>
    CIP4.Installer /action list  </pre> 
    
    <p>The CIP4ConnectionAttribute class defines a function called ProviderTypesEnumFromString that 
    will translate a string into a ProviderTypesEnum value.</p>

</body>
</html>
